.\"  -*- nroff -*-
.\" 
.\" twilio-utils - Command line utilities for Twilio users
.\" 
.\" Copyright 2013 Archie L. Cobbs <archie@dellroad.org>
.\" 
.\" Licensed under the Apache License, Version 2.0 (the "License"); you may
.\" not use this file except in compliance with the License. You may obtain
.\" a copy of the License at http://www.apache.org/licenses/LICENSE-2.0
.\" 
.\" Unless required by applicable law or agreed to in writing, software
.\" distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
.\" WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
.\" License for the specific language governing permissions and limitations
.\" under the License.
.\"
.\" $Id: twimsg.1.in 34 2014-12-08 22:49:28Z archie.cobbs $
.\"
.Dd May 17, 2013
.Dt TWIMSG 1
.Os
.Sh NAME
.Nm twimsg
.Nd Send outgoing SMS message via the Twilio REST API
.Sh SYNOPSIS
.Nm twimsg
.Bk -words
.Op Fl c Ar config
.Op Fl C Ar curlflag
.Op Fl e Ar encoding
.Op Fl F Ar number
.Op Fl f Ar file
.Op Fl m Ar URL
.Op Fl t Ar limit
.Ar number
.Ek
.Sh DESCRIPTION
.Nm
attempts to transmit a single outoing SMS message using the Twilio REST API
to the specified
.Ar number .
The message content is read from standard input, or the specified
.Ar file
if the
.Fl f
flag is used.
.Pp
The input is automatically truncated at the point at which it would exceed
.Ar limit
encoded bytes (default 140).
.Sh OPTIONS
.Bl -tag -width Ds
.It Fl c
Specify the configuration file.
.Pp
This file is simply a shell script that when sourced must define the
.Pa ACCOUNT_SID
and
.Pa AUTH_TOKEN
shell variables containing the corresponding Twilio credentials.
This file must also define
.Pa FROM_NUMBER
shell variable if the
.Fl F
flag is not used to specify the sending SMS phone number.
.Pp
If the
.Fl c
flag is not specified,
.Pa @defaultconf@
is assumed.
.It Fl C
Pass
.Ar curlflag
to
.Xr curl 1 .
.It Fl e
Specify input character encoding.
The default is UTF-8.
.Pp
Invalid character data is silently discarded.
.It Fl F
Specify the sending SMS phone number.
This flag is required if the configuration file does not define a default
.Pa FROM_NUMBER .
.It Fl f
Read the message content from the specified file instead of standard input.
.It Fl m
Send an MMS message using the image found at the specified
.Ar URL .
This flag may be repeated to send multiple images.
.It Fl t
Truncate the message when it would exceed
.Ar limit
bytes.
The default is 140, which keeps it within a single SMS message.
.Pp
Note Twilio supports automatic outgoing message concatenation;
to take advantage of this feature, use
.Fl t Ar 3200
instead.
.El
.Sh EXIT STATUS
.Nm
exits zero normally, or 1 if an error occurs.
.Pp
Errors returned from the Twilio REST API are reported to standard error.
.Sh SEE ALSO
.Xr curl 1 ,
.Xr smslen 1 ,
.Xr twiping 1 ,
.Xr twilog 1 .
.Sh AUTHOR
.An Archie L. Cobbs Aq archie@dellroad.org
